home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / tools / packer / uuinout / uuout.v1.03.doc < prev    next >
Text File  |  1995-03-09  |  12KB  |  293 lines
  1. $VER: uuOut.doc 1.03 (15.12.93)
  2.  
  3.            uuOut v1.03 by Nicolas Dade
  4.  
  5. uuOut version 1.03 is copyright 1993 by Nicolas Dade. All Rights
  6. Reserved. Permission is hereby granted for non-commercial
  7. duplication and distribution, and for distribution by BBSs which do
  8. not charge for downloads, and for distribution in disk collections
  9. which charge a nominal fee per disk. This is not shareware.
  10.  
  11. That out of the way, what is it?
  12.  
  13. It's a uudecoder to decode uuencoded text (an encoding scheme that
  14. is used to send binary files over links that only support textual
  15. characters---ie email and internet news)
  16.  
  17.  
  18. --Why is this decoder better than those already available?--
  19.  
  20. * It's very fast at decoding (and it uses a different, even faster
  21.   decode routine if a 68020 or higher is detected).
  22.   On top of that it uses a simplification of the Boyer-Moore search
  23.   algorithm when searching for 'begin' lines, so scanning files that
  24.   are largely not uuencoded-data for data is also very quick.
  25.   (It's 100% assembly)
  26.  
  27. * It sanity checks its input so that non-uuencoded data lines are
  28.   skipped over instead of being "decoded" and producing garbage.
  29.   Sanity checking includes checking trailing checksums, M's and X's,
  30.   and the 'size' line. Some sanity checking can be disabled in case
  31.   compatibility with the original uudecode is desired.
  32.  
  33. * It allows you to specify the output directory in which to place
  34.   the decoded file(s) so that they don't have to go to the
  35.   current directory, and paths in the encoded filenames can be
  36.   ignored or obeyed (needed dirs are created automatically)
  37.  
  38. * Output files have their protection flags set to reflect the
  39.   owner's rwx unix protection bits specified in the uuencoded
  40.   data.
  41.  
  42. * It will take its input from its standard input, as well as from
  43.   a file.
  44.  
  45. * It decodes all files encoded in its input, not just the first one.
  46.  
  47. * Partially complete files (missing data lines or missing 'end' lines)
  48.   don't mess up the other, complete, files.
  49.  
  50. * It does its own io buffering using user sizeable buffers, so
  51.   your harddrive won't be slowed by thrashing if uuOut's input
  52.   and output come from and go to that harddrive.
  53.  
  54. * It's pure and it's small---you can make it resident and it
  55.   won't cost you over 4K
  56.  
  57. * uuOut reports all errors and strange conditions with descriptive
  58.   error messages, and aborts if it is sent a break signal
  59.   (Control-C).
  60.  
  61.  
  62. --Requirements--:
  63.  
  64. WorkBench 2.04 or higher.
  65.  
  66.  
  67. --Use--:
  68.  
  69. the template for uuOut is: INFILE,OUTPATH,BUFSIZE/K/N,VERBOSE/S
  70.  
  71. INFILE....the file from which to read the uuencoded data. If no
  72.       INFILE is specified, standard input is used.
  73.  
  74. OUTPATH...a directory from which the uudecoded files's location is
  75.       based. Usually that means that the output files go in
  76.       OUTPATH, but if the output file's name contains a path
  77.       along with a filename (i.e. "dir1/dir2/filename") then
  78.       the uudecoded file will appear in OUTPATH/dir1/dir2/filename.
  79.       (the directories "dir1" and "dir2" are created if they do
  80.       not already exist)
  81.       If OUTPATH is not specified the current-directory is used
  82.       in its place.
  83.       If this directory does not exist it too will be created.
  84.  
  85. BUFSIZE...allows you to specify the size of the input and
  86.       output buffers uuOut should use in kilobytes. The default
  87.       is 32K which is a little small for a harddrive to
  88.       harddrive decode. Try 150K or higher, until the accesses
  89.       to the harddrive become a second or so apart. If there
  90.       isn't sufficient memory available to allocate buffers of
  91.       the specified size, uuOut keeps trying small and smaller
  92.       sizes (half as large each time) until the buffer would be
  93.       smaller than 1K, at which point uuOut gives up and aborts
  94.       with an error message explaining that there isn't enough
  95.       memory in the system for the buffers. Note that if you
  96.       don't have 2K free you've got more problems on your hands
  97.       than uuOut refusing to run. :)
  98.  
  99. USEBASENAME...instead of (if need be) creating directories and placing
  100.       the uudecoded files in those directories, all uudecoded files
  101.       are created in the current-directory (or OUTPATH if specified).
  102.       i.e. "begin 644 dir1/dir2/file" would be decoded into
  103.       <current-dir>/file or OUTPATH/file, instead of
  104.       <current-dir>/dir1/dir2/file or OUTPATH/dir1/dir2/file.
  105.  
  106. IGNORETERMINATION...ignores all data from the last of the data characters
  107.       to the EOL of each line. This is to be used only when not using
  108.       it causes bad checksum error messages but you think the data is
  109.       good. It makes uuOut act like the original unix uudecode, which
  110.       means that the data can be followed by anything, including
  111.       things the usual input-checking code doesn't know about.
  112.  
  113. VERBOSE...uuOut reports each step it takes to standard-error.
  114.  
  115.  
  116. --Examples--:
  117.  
  118. To decode any uuencoded files in the file "t:FreshEmail.txt" and
  119. create the paths+files starting from the "work:" directory
  120.  
  121.   uuOut t:FreshEmail.txt work:
  122.  
  123. and to use 150K io buffers instead of the default 32K when doing this
  124.  
  125.   uuOut t:FreshEmail.txt work: BUFSIZE=150
  126.  
  127. and to have all the files go in the work: directory and not some
  128. sub-directories of work:
  129.  
  130.   uuOut t:FreshEmail.txt work: BUFSIZE=150 USEBASENAME
  131.  
  132. To decode the standard input stream and create the output files
  133. in the current directory
  134.  
  135.   uuOut
  136.  
  137. (kind of easy, no?)
  138. And to decode the standard input stream and create the output
  139. files in "t:"
  140.  
  141.   uuOut OUTPATH=t:
  142.  
  143. just saying "uuOut t:" will not work because t: will be
  144. interpreted to be the name of the input file, and uuOut will then
  145. try to open and read from the "file" t:, find that it cannot, and
  146. abort with an error message.
  147.  
  148. Decoding data that is stored in multiple files can be done with
  149. the help of the C= join command: (BTW if you're just going to feed
  150. the data to uuOut then don't bother with multiple files, they just
  151. slow things down---instead create one giant file and feed it to uuOut)
  152.  
  153.   run join file1 file2 file3 ... to pipe:file
  154.   uuOut pipe:file
  155.  
  156. or, if you have set the __pchar local variable to | and have the
  157. pipe command installed, then it is easier to use
  158.  
  159.   join file1 file2 file3 ... to out: | uuOut
  160.  
  161. (yes, the C= shell can do nameless piping, it's just not documented.)
  162. Or if you have csh installed,
  163.  
  164.   cat file1 file2 file3 ... | uuOut
  165.  
  166. And as usual, to see the template
  167.  
  168.  uuOut ?
  169.  
  170. and to see the full built-in help and copyright text, give a
  171. second "?" at the prompt following the template.
  172.  
  173.  
  174. --Speed Comparisons--:
  175.  
  176. On a 7.14MHz NTSC 68000 based Amiga (ie A500, A1000 or A2000) using
  177. the command line "uuOut ram:440KByteFile ram:", decoding the
  178. 440Kbyte file which contains a 310 KByte uuencoded file:
  179.  
  180. using:      version:    takes:        speed:
  181. uuOut      1.03        5.7 secs       77Kb/s
  182. UUDecodeX 1.02           27.7 secs       16KB/s
  183. UUxT      2.2           41.3 secs       11Kb/s
  184. uudecode  ?**           64.3 secs    7Kb/s
  185.  
  186. ** by Mark Horton and Alan J. Rosenthal. I couldn't find any version
  187. information.
  188.  
  189. I don't have a 68020 Amiga handy, but on a 22MHz 68030 based
  190. A2000 the same commands took:
  191.  
  192. using:      version:    takes:        speed:
  193. uuOut      1.03        1.0 secs       440Kb/s
  194. UUDecodeX 1.02        4.7 secs    94KB/s
  195. UUxT      2.2        7.2 secs    61Kb/s
  196. uudecode   ?           10.0 secs    44Kb/s
  197.  
  198.  
  199. --Sanity Checking of Input--:
  200.  
  201. uuOut's input-checking keeps it from trying to decode lines that
  202. obviously aren't data lines, and it's difficult to fool, unlike a
  203. certain other uudecoder that advertises this feature. uuOut insists
  204. a data line contain only the characters 0x20 (space) through 0x40
  205. (backquote) inclusive (0x40 is considered equivalent to 0x20), and
  206. have the right number of characters (the first byte of a data line
  207. is a count). Furthermore the data line must end with (optionally)
  208. a checksum character, (optionally) an X or M, and then either a
  209. LF or a CR, and the checksum, if it is present, must be correct.
  210. (If a line looks good except that it's checksum is bad, uuOut
  211. ignores the data in the line, but warns you that a line that
  212. looked like data but had a bad checksum is being skipped.)
  213.  
  214. This means that mail and news header lines aren't considered data
  215. because the header names contain lowercase characters or, if they
  216. don't, rarely (that's the .1% of the time) contain the right
  217. number of characters. You _can_ 99.9% of the time pass mail or news
  218. right through uuOut without stripping off anything. Furthermore
  219. uuOut does not give up after decoding one file, but rather continues
  220. looking for and decoding any more uuencoded files in the text.
  221.  
  222. On top of that, if there is a 'size' line after the 'end' line,
  223. uuOut will check to see if the file size specified in the 'size' line
  224. matches the actual size of the file just created, and warn you if it
  225. does not. This protects you against missing parts of a multi-part
  226. file, and the very rare lines that fool uuOut's line-by-line input
  227. checking. If you think the data is good, then first try editing the
  228. file containing the uuencoded data so that it contains only the
  229. 'begin' line, the data, and the 'end' and 'size' lines. Pass this
  230. through uuOut. If uuOut says the size line is still wrong then
  231. the data probably is bad, or part of the data is missing.
  232.  
  233. --I can be reached at--:
  234.  
  235.  Nicolas Dade
  236.  405 W Delaware
  237.  Urbana, IL 61801  (USA)
  238. nicolas-dade@uiuc.edu
  239.  
  240.  
  241. --FAQ--:
  242.  
  243. Q: Why does my shell not come back after I look at the template or
  244. the help text?
  245.  
  246. A: Because if you just press <return> at the template prompt uuOut
  247. thinks it's in the "decode standard input" case, and whatever you
  248. type after that goes into uuOut, not your shell. To get out of it
  249. you have to send uuOut an end-of-file, which is control-\ on the
  250. standard amiga keymaps. uuOut will exit, but it will also warn you
  251. that no 'begin' line was found in its input file (or, if you typed
  252. 'begin nnn f*', that no 'end' line was found.) (Unless, of course,
  253. you then also typed 'end' :)
  254.  
  255.  
  256. --History--:
  257.  
  258. 1.00  o First version debugged enough to pass around
  259. 1.01  o Changed verbose output to go to standard-error if one is
  260.     defined instead of standard-out. Standard-out is still
  261.     used as a fallback. (pr_CES instead of pr_COS)
  262. 1.02  o Since Alan T Shutko so kindly sent me the code for the checksum,
  263.     I added checksum checking.
  264.       o Added size line check.
  265.       o Fixed bug where a begin line that was loaded at the end of the
  266.     buffer was passed over. This showed up easily when you typed
  267.     the 'begin' line into a console window yourself.
  268.       o And fixed the 'we're stuck in a loop' code. Now lines like
  269.     "''" will not trigger it. Actually the bug was more complicated
  270.     and more general than this. There were a couple places where
  271.     the logic was screwy and a the 'infinite loop' condition could
  272.     be detected when it wasn't the case.
  273.       o Added checking for early 'begin' lines. Now uuOut checks for a
  274.     'begin' line even if the previous file's 'end' line has not yet
  275.     been found. When one is found a warning is, of course, issued.
  276.       o Thanks to Marcus Damberger for testing uuOut many times on his
  277.     030 machine.
  278.       o Added USEBASENAME and the automatic directory creation due to
  279.     David Zaroski's email/suggestion. (but not after a fight :)
  280.       o Changed, again because David Zaroski pointed it out to me,
  281.     the 'begin' line detection code. begin lines now must match:
  282.     begin<sp>#<sp>#[0-7][0-7][0-7][0-7]<sp>#<sp>(~<sp>)*<EOL>
  283.       o Added check for 'M' terminated lines, and IGNORETERMINATION
  284.     because David Zaroski managed to find a uuencoded file with
  285.     each line terminated with an 'M'.
  286. 1.03  o No changes, but I upped the version number so that it matched
  287.     that of the uuIn and uuPrepare with which it is going to be
  288.     distributed. Also they are too many betas of v1.02 floating
  289.     around. Going to 1.03 makes all those people think that they
  290.     should upgrade.
  291.       o Thanks to Olivier Jeannet for testing the final version.
  292.  
  293.